Обновление документации
На днях состоялось обновление документации для продукта KOMRAD. Спешим раскрыть все секреты касательно того, как это произошло.
Немного истории
3 года назад мы готовили сертификационную документацию по требованию ФСТЭК и задумались над тем, что сложно поддерживать её в актуальном состоянии. Дело в том что сертификационная документация очень долго обновляется и вообще это сложный процесс для всех:
- для заказчика (он постоянно должен у спрашивать саппорта "а может ли продукт то, что не описано в руководстве, и как это сделать?"
- для разработчика (согласовать новую версию руководства с ФСТЭК, а у нас оно лежит на диске, пересчитать КС и отправить всем)
- для ФСТЭКа ничего кроме руководства не меняется, но документация все равно проходит все формальные процессы в ведомстве, и это может быть очень долго
- для саппорта (у саппорта должна быть либо своя база знаний, либо мини-инструкции на любой случай)
Antora
Поэтому мы задумались о том, чтобы иметь электронную документацию, которая потенциально решила бы все наши проблемы. В первый раз мы не выбирали долго, форкнули готовый проект на Antora и переделали её под себя настроили CI/CD, начали документировать. Антора немного специфична, например, формат разметки текста в ней asciidoc. Поскольку это была наша первая электронная документация, мы хотели быстро её сделать и быстро выложить. С первым мы справились действительно быстро, сделали простое деление на руководство администратора и оператора, остальные статьи были отсылками к другим документам, но, в итоге, мы посчитали, что более структурировано будет выглядеть архитектура с продуктовой логикой, вдохновлялись документацией.
Стоит отметить, что у таких проектов, как Антора есть своя философия, там есть своя структура папок, есть рекомендации по CI, но мы, в большей степени, её игнорировали с самого начала. И не стоит забывать, что мы переделывали форк под себя, мы пытались оградить UI и бэкенд специалистов от работы, связанной с документацией, но повышать зависимости надо и документация начала ломаться. Большой проблемой стал поиск, когда локальный поиск сломался, мы попробовали его переписать, но безуспешно, UI жаловался на легаси код и отклонял наши хотелки, например, возможность зумить изображения. Вершиной всего стало то, что из-за неверной настройки нам пришлось бы потратить много времени на добавление новых версий, хотя, в репозитории документации уже были готовые ветки, из которых просто нужно было собрать версии.
Муки выбора
Есть достаточное количество проектов для электронной документации. В большей степени, они используют Markdown, очевидно, он проще и популярнее, поэтому для нас это было не ограничением, но препятствием. Мы рассматривали такие проекты:
По набору функций нас впечатлили Docusaurus и Gitbook, но у Docusaurus больше запас на развитие документации, поэтому мы сделали выбор в его пользу. Развитие - это фичи, которые можно опционально подключить, в docusaurus - это плагины, сейчас их не так много, по причине обновления docusaurus до версии 3, на 2-й версии их было огромное количество, но не все ещё добавили поддержку 3-й версии.
Docusaurus
Новые фичи:
- локальный поиск
- зум изображений
- работа с формами
- тёмная тема
- версионирование
- новое индексирование
Мы перенесли все документы в их исходном виде и добавили ещё одну версию 4.5.Х, сейчас она в стадии Beta и выдаётся по запросу, но уже сейчас есть доступ к её актуальной документации. Новые функции и новая логика элементов и страниц будет правиться только для версии 4.5.